LineFormat

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.sadun.text.ffp
Class LineFormat

java.lang.Object
  org.sadun.text.ffp.LineFormat

All Implemented Interfaces:: java.lang.Cloneable

public class LineFormat
extends java.lang.Object
implements java.lang.Cloneable

An ojbect of this class holds details of a specific logical line format and can parse it from core memory. A logical line can be composed by several consecutive physical lines, separated by a line separator character sequence.

A LineFormat is built by declaring the expected fields and used by invoking the parse(String) method. Three ways are available to declare the expected fields:

One of the defineField() overloads.

The overload with most parameters allows to specify the physical line containing the field, a name for the field, a type, its zero-based start and end indexes (end excluded) and a possible image - a denotation that must be matched by the field value once parsed.

Type	Image
`Type.CONSTANT`	required, the constant value
`Type.ALFA`	optional, null or a regular expression which must be matched by the value
`Type.NUMERIC`	optional, null or a `NumberFormat` string which will be used to parse the value
`Type.UNDEFINED`	ignored

For example,

  format.defineField(0, 5, Type.NUMERIC);
  format.defineField(5, 7, Type.CONSTANT, "aa");
  format.defineField(7, 12, Type.NUMERIC);

One of the defineNextField() overloads.
defineNextField(int, int, Type, String) behaves exactly as defineField(int, int, int, Type, String), but the start index is implicit: the LineFormat keeps track a "current start" index which is updated with each definition.
For example,
```
  format.defineNextField(5, Type.NUMERIC);
  format.defineNextField(7, Type.CONSTANT, "aa");
  format.defineNextField(12, Type.NUMERIC);
 
```
A line image, by using a declareLineImage() overload. Line images use sequences of characters (separated by spaces) to denote types:

Symbol Type

@ Type.ALFA

# Type.NUMERIC

any character Type.CONSTANT

/b blank in Type.CONSTANT

// forward slash in Type.CONSTANT

For example,
```
  format.declareLineImage("##### aa #####");
 
```

For each method, overloads which accept a physical line number as parameter or not are provided: if the parameter is absent, the physical line number is intended 1 (the common case of parsing a single line).

A LineFormat can be copied in whichever moment, and the resulting copy is independent from the original object. This allows to minimize the amount of declarations necessary for creating LineFormats for similar lines.

When parse(String) is invoked, the object attempts to parse the passed text according to the format definition. If the parsing fails, a FFPParseException subexception is thrown. If the line is parsed correctly but some characters are still existing before the line separator:

if isFailOnTrailingChars() is true a TrailingCharactersException is thrown;
else, the remaining characters are ignored, but a warning is logged on the FlatFileParser.LOGGER_CHANNEL_NAME channel.

isFailOnTrailingChars() is initialized on construction depending on the value of the public static field defaultFailOnTrailingChars, which is by default set to true (i.e. indicating that an exception should be raised on trailing characters).

Version:: 1.0
Author:: Cristiano Sadun

Nested Class Summary
`class`	`LineFormat.FieldInfo` A class describing a field.

Field Summary
`static boolean`	`defaultFailOnTrailingChars` This member controls the default value of the `failOnTrailingChars` property.

Constructor Summary
`LineFormat()` Create a LineFormat, for reading a logical line.
`LineFormat(java.lang.String name)` Create a LineFormat with a name, for reading a logical line.

Method Summary
`LineFormat`	`createCopy()` Create an independent copy of the format.
`void`	`declareLineImage(int physicalLine, java.lang.String image)` This method allows to declare quickly a line format by providing an image.
`void`	`declareLineImage(java.lang.String image)` This method allows to declare quickly a line format by providing an image.
`void`	`defineField(int start, int end)` Define a field as being at the given start-end position.
`void`	`defineField(int physicalLine, int start, int end)` Define a field as being in the given physical line and at the given start-end position.
`void`	`defineField(int physicalLine, int start, int end, Type type)` Define a field as being in the given physical line and at the given start-end position.
`void`	`defineField(int physicalLine, int start, int end, Type type, java.lang.String image)` Define a field as being in the given physical line and at the given start-end position.
`void`	`defineField(int start, int end, Type type)` Define a field as being at the given start-end position and having the given type.
`void`	`defineField(int physicalLine, java.lang.String name, int start, int end)` Define a field as being in the given physical line and at the given start-end position.
`void`	`defineField(int physicalLine, java.lang.String name, int start, int end, Type type)` Define a field as being in the given physical line and at the given start-end position.
`void`	`defineField(int physicalLine, java.lang.String name, int start, int end, Type type, java.lang.String image)` Define a field as being in the given physical line and at the given start-end position.
`void`	`defineField(java.lang.String name, int start, int end)` Define a field as being at the given start-end position and having the given name.
`void`	`defineField(java.lang.String name, int start, int end, Type type)` Define a field as being at the given start-end position and having the given name and type.
`void`	`defineFields(int[][] positions)` Define fields using a positions array.
`void`	`defineFields(int physicalLine, int[][] positions)` Define fields in the given physical line using a positions array.
`void`	`defineNextField(int end)` Define a field as being located from the current start position to the given end position (excluded).
`void`	`defineNextField(int physicalLine, int end)` Define a field as being in the given physical line, from the current start position to the given end position (excluded).
`void`	`defineNextField(int physicalLine, int end, Type type)` Define a field as being in the given physical line, having the given type and being located from the current start position to the given end position (excluded).
`void`	`defineNextField(int physicalLine, int end, Type type, java.lang.String image)` Define a field as being in the given physical line, having the given type and image and being located from the current start position to the given end position (excluded).
`void`	`defineNextField(int physicalLine, java.lang.String name, int end)` Define a field as being in the given physical line, having the given name and being located from the current start position to the given end position (excluded).
`void`	`defineNextField(int physicalLine, java.lang.String name, int end, Type type)` Define a field as being in the given physical line, having the given name and type and being located from the current start position to the given end position (excluded).
`void`	`defineNextField(int physicalLine, java.lang.String name, int end, Type type, java.lang.String image)` Define a field as being in the given physical line, having the given name, type and image and being located from the current start position to the given end position (excluded).
`void`	`defineNextField(int end, Type type)` Define a field as having the given type and being located from the current start position to the given end position (excluded).
`void`	`defineNextField(int end, Type type, java.lang.String image)` Define a field as having the given type and image and being located from the current start position to the given end position (excluded).
`void`	`defineNextField(java.lang.String name, int end)` Define a field as having the given name and being located from the current start position to the given end position (excluded).
`void`	`defineNextField(java.lang.String name, int end, Type type)` Define a field as having the given name and being located from the current start position to the given end position (excluded), and given type
`void`	`defineNextField(java.lang.String name, int end, Type type, java.lang.String image)` Define a field as having the given name and being located from the current start position to the given end position (excluded), and given type and image
`void`	`defineNextFields(int[] positions)` Define consecutive fields using a positions array.
`void`	`defineNextFields(int physicalLine, int[] positions)` Define consecutive fields in the given physical line using a positions array.
`static java.lang.String`	`extract(java.lang.CharSequence line, int start, int end)` An utility method to extracts a portion of a physical line.
`java.lang.String`	`formatValuesAsXML(int lineCount, java.lang.String[] values)` An utility method to format a set of values to an XML format, according to this `LineFormat`.
`java.lang.String`	`formatValuesAsXML(java.lang.String[] values)` An utility method to format a set of values to an XML format, according to this `LineFormat`.
`static LineFormat`	`fromImage(java.lang.String image)` Allows to create a LineFormat object directly from an image.
`static LineFormat`	`fromImage(java.lang.String name, java.lang.String image)` Allows to create a named LineFormat object directly from an image.
`int`	`getFieldsCount()` Return the number of fields in the logical line.
`int`	`getFieldsCount(int physicalLine)` Return the number of fields in the physical line.
`java.lang.String`	`getLineSeparator()` Return the line separator.
`java.lang.String`	`getName()` Return the name of this line format.
`int`	`getPhysicalLinesCount()` Return the physical lines count at the moment of call.
`boolean`	`isFailOnTrailingChars()` Return whether or not parsing must fails if a line is parsed correctly but not all its characters are consumed.
`java.util.Iterator`	`iterator()` Return an iterator on this format's `LineFormat.FieldInfo` set.
`static java.lang.String`	`makeConstantImage(java.lang.String s)` Return a string constant translated to the image syntax recognized by this class.
`java.lang.String[]`	`parse(java.lang.String s)` Parse the given line basing on the format.
`java.lang.String[]`	`parse(java.lang.String s, boolean autoTrim)` Parse the given line basing on the format.
`java.lang.String`	`parseToXml(java.lang.String s)` An utility method, which parses a line, and returns its XML fragment representation.
`java.lang.String`	`parseToXml(java.lang.String s, boolean autoTrim)` An utility method, which parses a line, and returns its XML fragment representation.
`void`	`setFailOnTrailingChars(boolean failOnTrailingChars)` Set whether or not parsing must fails if a line is parsed correctly but not all its characters are consumed.
`void`	`setLineSeparator(java.lang.String lineSeparator)` Set the line separator.
`java.lang.String`	`toString()` Return a human-readable description of the format.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

defaultFailOnTrailingChars

public static boolean defaultFailOnTrailingChars

This member controls the default value of the failOnTrailingChars property. It is set to true when the class is loaded.

Constructor Detail

LineFormat

public LineFormat(java.lang.String name)

Create a LineFormat with a name, for reading a logical line.

A logical line may be composed by multiple physical lines separated by a line separator.

LineFormat

public LineFormat()

Create a LineFormat, for reading a logical line.

A logical line may be composed by multiple physical lines separated by a line separator.

Method Detail

getName

public java.lang.String getName()

Return the name of this line format.

Returns:: the name of this line format.

getLineSeparator

public java.lang.String getLineSeparator()

Return the line separator. By default, the line separator is the value of the line.separator system property.

Returns:: Returns the lineSeparator.

setLineSeparator

public void setLineSeparator(java.lang.String lineSeparator)

Set the line separator. By default, the line separator is the value of the line.separator system property.

Parameters:: lineSeparator - The lineSeparator to set.

getPhysicalLinesCount

public int getPhysicalLinesCount()

Return the physical lines count at the moment of call.

Note that if defineField(int, int, int)is invoked declaring a field into a greater physical line, the count returned by this method will adjust accordingly.

Returns:: the physical lines count at the moment of call.

extract

public static java.lang.String extract(java.lang.CharSequence line,
                                       int start,
                                       int end)
                                throws IllegalRangeException

An utility method to extracts a portion of a physical line.

Parameters:: line - the character array containing the physical line; start - the start index; end - the end index
Returns:: the String comprised between start and end (excluded).
Throws:: IllegalRangeException - if the given range is not valid

defineFields

public void defineFields(int physicalLine,
                         int[][] positions)

Define fields in the given physical line using a positions array. As many fields as elements in the array are defined. Each element must be a two-integer array containing start and end position of the field (excluded).

Parameters:: positions - as many fields as elements in the array are defined. Each element of the array must be a two-integer array containing start and end position of the field (excluded).

defineFields

public void defineFields(int[][] positions)

Define fields using a positions array. As many fields as elements in the array are defined. Each element must be a two-integer array containing start and end position of the field (excluded).

Parameters:: positions - as many fields as elements in the array are defined. Each element of the array must be a two-integer array containing start and end position of the field (excluded).